From 6b4ef0237c147a3fe02b446bdc831a228c5a8da7 Mon Sep 17 00:00:00 2001 From: Chris Beams Date: Sun, 9 Oct 2011 07:54:33 +0000 Subject: [PATCH] Add code examples to and polish @Bean Javadoc --- .../context/annotation/Bean.java | 94 ++++++++++++++----- 1 file changed, 72 insertions(+), 22 deletions(-) diff --git a/org.springframework.context/src/main/java/org/springframework/context/annotation/Bean.java b/org.springframework.context/src/main/java/org/springframework/context/annotation/Bean.java index d154d42e4bc..b6bda429498 100644 --- a/org.springframework.context/src/main/java/org/springframework/context/annotation/Bean.java +++ b/org.springframework.context/src/main/java/org/springframework/context/annotation/Bean.java @@ -1,5 +1,5 @@ /* - * Copyright 2002-2009 the original author or authors. + * Copyright 2002-2011 the original author or authors. * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. @@ -27,34 +27,83 @@ import org.springframework.beans.factory.annotation.Autowire; /** * Indicates that a method produces a bean to be managed by the Spring container. The * names and semantics of the attributes to this annotation are intentionally similar - * to those of the {@code } element in the Spring XML schema. - * - *

Note that the {@code @Bean} annotation does not provide attributes for scope, - * primary or lazy. Rather, it should be used in conjunction with {@link Scope @Scope}, - * {@link Primary @Primary}, and {@link Lazy @Lazy} annotations to achieve - * those semantics. The same annotations can also be used at the type level, e.g. for - * component scanning. + * to those of the {@code } element in the Spring XML schema. For example: + * 

+ *     @Bean
+ *     public MyBean myBean() {
+ *         // instantiate and configure MyBean obj
+ *         return obj;
+ *     }
* *

While a {@link #name()} attribute is available, the default strategy for determining * the name of a bean is to use the name of the Bean method. This is convenient and * intuitive, but if explicit naming is desired, the {@code name()} attribute may be used. * Also note that {@code name()} accepts an array of Strings. This is in order to allow * for specifying multiple names (i.e., aliases) for a single bean. + * 

+ *     @Bean(name={"b1","b2"}) // bean available as 'b1' and 'b2', but not 'myBean'
+ *     public MyBean myBean() {
+ *         // instantiate and configure MyBean obj
+ *         return obj;
+ *     }
* - *

The @Bean annotation may be used on any methods in an @Component - * class, in which case they will get processed in a configuration class 'lite' mode where + *

Note that the {@code @Bean} annotation does not provide attributes for scope, + * primary or lazy. Rather, it should be used in conjunction with {@link Scope @Scope}, + * {@link Primary @Primary}, and {@link Lazy @Lazy} annotations to achieve + * those semantics. For example: + * 

+ *     @Bean
+ *     @Scope("prototype")
+ *     public MyBean myBean() {
+ *         // instantiate and configure MyBean obj
+ *         return obj;
+ *     }
+ * + *

Typically, {@code @Bean} methods are declared within {@code @Configuration} + * classes. In this case, bean methods may reference other @Bean methods + * on the same class by calling them directly. This ensures that references between + * beans are strongly typed and navigable. Such so-called 'inter-bean references' are + * guaranteed to respect scoping and AOP semantics, just like getBean lookups + * would. These are the semantics known from the original 'Spring JavaConfig' project + * which require CGLIB subclassing of each such configuration class at runtime. As a + * consequence, {@code @Configuration} classes and their factory methods must not be + * marked as final or private in this mode. For example: + * 

+ * @Configuration
+ * public class AppConfig {
+ *     @Bean
+ *     public FooService fooService() {
+ *         return new FooService(fooRepository());
+ *     }
+ *     @Bean
+ *     public FooRepository fooRepository() {
+ *         return new JdbcFooRepository(dataSource());
+ *     }
+ *     // ...
+ * }
+ * + *

{@code @Bean} methods may also be declared wihtin any {@code @Component} class, in + * which case they will get processed in a configuration class 'lite' mode in which * they will simply be called as plain factory methods from the container (similar to - * factory-method declarations in XML). The containing component classes remain - * unmodified in this case, and there are no unusual constraints for factory methods. + * {@code factory-method} declarations in XML). The containing component classes remain + * unmodified in this case, and there are no unusual constraints for factory methods, + * however, scoping semantics are not respected as described above for inter-bean method + * invocations in this mode. For example: + * 

+ * @Component
+ * public class Calculator {
+ *     public int sum(int a, int b) {
+ *         return a+b;
+ *     }
+ *
+ *     @Bean
+ *     public MyBean myBean() {
+ *         return new MyBean();
+ *     }
+ * }
* - *

As an advanced mode, @Bean may also be used within @Configuration - * component classes. In this case, bean methods may reference other @Bean methods - * on the same class by calling them directly. This ensures that references between beans - * are strongly typed and navigable. Such so-called 'inter-bean references' are guaranteed to - * respect scoping and AOP semantics, just like getBean lookups would. These are - * the semantics known from the original 'Spring JavaConfig' project which require CGLIB - * subclassing of each such configuration class at runtime. As a consequence, configuration - * classes and their factory methods must not be marked as final or private in this mode. + *

See @{@link Configuration} Javadoc for further details including how to bootstrap + * the container using {@link AnnotationConfigApplicationContext} and friends. * *

A note on {@code BeanFactoryPostProcessor}-returning {@code @Bean} methods

*

Special consideration must be taken for {@code @Bean} methods that return Spring @@ -81,12 +130,12 @@ import org.springframework.beans.factory.annotation.Autowire; * @author Chris Beams * @author Juergen Hoeller * @since 3.0 - * @see org.springframework.stereotype.Component * @see Configuration * @see Scope * @see DependsOn * @see Lazy * @see Primary + * @see org.springframework.stereotype.Component * @see org.springframework.beans.factory.annotation.Autowired * @see org.springframework.beans.factory.annotation.Value */ @@ -110,7 +159,8 @@ public @interface Bean { /** * The optional name of a method to call on the bean instance during initialization. * Not commonly used, given that the method may be called programmatically directly - * within the body of a Bean-annotated method. + * within the body of a Bean-annotated method. Default value is {@code ""}, indicating + * that no init method should be called. */ String initMethod() default "";