diff --git a/spring-framework-reference/src/beans.xml b/spring-framework-reference/src/beans.xml index 7e5e9b1a6c6..ec3d3fa9c43 100644 --- a/spring-framework-reference/src/beans.xml +++ b/spring-framework-reference/src/beans.xml @@ -6026,325 +6026,9 @@ public @interface MovieQualifier { -
- Java-based configuration - - Starting with Spring 3.0 many of the features provided by the Spring JavaConfig - project have been added to the core Spring Framework. This allows - you to define beans using Java rather than using the traditional XML - files. - - The central artifact in Spring's new Java-configuration support is - the @Configuration-annotated class. These - classes consist principally of - @Bean-annotated methods that define - instantiation, configuration, and initialization logic for objects that - will be managed by the Spring IoC container. - -
- Using the <interfacename>@Configuration</interfacename> - annotation - - Annotating a class with the - @Configuration indicates that the class - may be used by the Spring IoC container as a source of bean definitions. - The simplest possible @Configuration - class would read as follows: - - An application may make use of just one - @Configuration-annotated class, or many. - @Configuration is meta-annotated as a - @Component, therefore - Configuration-classes are candidates for component-scanning and may also - take advantage of @Autowired annotations - at the field and method level but not at the constructor level. - Configuration-classes must also have a default constructor. Externalized - values may be wired into Configuration-classes using the - @Value annotation. -
- -
- Using the <interfacename>@Bean</interfacename> annotation - - @Bean is a method-level annotation - and a direct analog of the XML <bean/> element. The - annotation supports some of the attributes offered by - <bean/>, such as: init-method, - destroy-method, - autowiring - and name. - -
- Declaring a bean - - To declare a bean, simply annotate a method with the - @Bean annotation. Such a method - will be used to register a bean definition within a BeanFactory - of the type specified as the methods return value. By default, - the bean name will be the same as the method name (see bean naming for details on how to - customize this behavior). The following is a simple example of a - @Bean method declaration: - - - For comparison sake, the configuration above is exactly - equivalent to the following Spring XML: - - ]]> - - Both will result in a bean named transferService - being available in the BeanFactory or - ApplicationContext, bound to an object instance of type - TransferServiceImpl: com.acme.TransferServiceImpl - ]]> -
- -
- Injecting dependencies - - When @Beans have dependencies on - one another, expressing that dependency is as simple as having one - bean method call another: - - In the example above, the foo bean recevies a - reference to bar via constructor injection. -
- -
- Receiving lifecycle callbacks - - Beans created in a Configuration-class supports the regular - lifecycle callbacks. Any classes defined with the @Bean annotation can - use the @PostConstruct and @PreDestroy annotations from JSR-250, see - the section on JSR-250 - annotations for further details. - - The regular Spring lifecycle callbacks are fully - supported as well. If a bean implements InitializingBean, - DisposableBean, or Lifecycle, their - respective methods will be called by the container. - - The standard set of *Aware interfaces such as - BeanFactoryAware, - BeanNameAware, - MessageSourceAware, - ApplicationContextAware, - etc. are also fully supported. - - The @Bean annotation supports - specifying arbitrary initialization and destruction callback methods, - much like Spring XML's init-method and - destroy-method attributes to the bean - element: - - Of course, in the case of Foo above, it would be - equally as valid to call the init() method directly - during construction: - - - Remember that because you are working directly in Java, you - can do anything you like with your objects, and do not always need - to rely on the container! - -
- -
- Specifying bean scope - -
- Using the <interfacename>@Scope</interfacename> - annotation - - You can specify that your beans defined with the - @Bean annotation should have a - specific scope. You can use any of the standard scopes specified in - the Bean Scopes - section. - - The StandardScopes class provides string - constants for each of these four scopes. SINGLETON is the default, - and can be overridden by using the - @Scope annotation: -
- -
- <code>@Scope and scoped-proxy</code> - - Spring offers a convenient way of working with scoped - dependencies through scoped - proxies. The easiest way to create such a proxy when using - the XML configuration is the <aop:scoped-proxy/> - element. Configuring your beans in Java with a @Scope annotation - offers equivalent support with the proxyMode attribute. The default - is no proxy (ScopedProxyMode.NO) but you can - specify ScopedProxyMode.TARGET_CLASS or - ScopedProxyMode.INTERFACES. - - If we were to port the the XML reference documentation scoped - proxy example (see link above) to our - @Bean using Java, it would look like - the following: -
- -
- Lookup method injection - - As noted in the core documentation, lookup method - injection is an advanced feature that should be comparatively - rarely used. It is useful in cases where a singleton-scoped bean has - a dependency on a prototype-scoped bean. Using Java for this type - of configuration provides a natural means for implementing this pattern. - Note that the example below is adapted from the example - classes and configuration in the core documentation linked above. - - - JavaConfig can easily create a subclass of - CommandManager where the abstract - createCommand() is overridden in such a way that it - 'looks up' a brand new (prototype) command object: -
-
- -
- Customizing bean naming - - By default, Configuration-classes uses a - @Bean method's name as the name of the - resulting bean. This functionality can be overridden, however, using - the name attribute. -
-
-
-
- Classpath scanning for managed components + Classpath scanning, managed components and writing configurations + using Java Thus far most of the examples within this chapter have used XML for specifying the configuration metadata that produces each @@ -6358,6 +6042,18 @@ public class AppConfig { the candidate components by scanning the classpath and matching against filters. + + Starting with Spring 3.0 many of the features provided by the + Spring JavaConfig + project have been added to the core Spring Framework. This + allows you to define beans using Java rather than using the traditional + XML files. Take a look at the + @Configuration, + @Bean, + @Value annotations for how to use these + new features. + +
<interfacename>@Component</interfacename> and further stereotype annotations @@ -6582,6 +6278,410 @@ public class JpaMovieFinder implements MovieFinder {
+
+ Using the <interfacename>@Configuration</interfacename> + annotation + + The central artifact in Spring's new Java-configuration support is + the @Configuration-annotated class. These + classes consist principally of + @Bean-annotated methods that define + instantiation, configuration, and initialization logic for objects that + will be managed by the Spring IoC container. + + Annotating a class with the + @Configuration indicates that the class + may be used by the Spring IoC container as a source of bean definitions. + The simplest possible @Configuration + class would read as follows: + + An application may make use of one + @Configuration-annotated class, or many. + @Configuration is meta-annotated as a + @Component, therefore + Configuration-classes are candidates for component-scanning and may also + take advantage of @Autowired annotations + at the field and method level but not at the constructor level. + Configuration-classes must also have a default constructor. Externalized + values may be wired into Configuration-classes using the + @Value annotation. +
+ +
+ Using the <interfacename>@Bean</interfacename> annotation + + @Bean is a method-level annotation + and a direct analog of the XML <bean/> element. The + annotation supports some of the attributes offered by + <bean/>, such as: init-method, + destroy-method, + autowiring + and name. + + You can use the @Bean annotation in a Configuraton-class or in a + Component-class. + +
+ Declaring a bean + + To declare a bean, simply annotate a method with the + @Bean annotation. Such a method will be + used to register a bean definition within a BeanFactory + of the type specified as the methods return value. By default, the + bean name will be the same as the method name (see bean naming for details on how to + customize this behavior). The following is a simple example of a + @Bean method declaration: + + + For comparison sake, the configuration above is exactly + equivalent to the following Spring XML: + + ]]> + + Both will result in a bean named transferService + being available in the BeanFactory or + ApplicationContext, bound to an object instance of type + TransferServiceImpl: com.acme.TransferServiceImpl + ]]> +
+ +
+ Injecting dependencies + + When @Beans have dependencies on + one another, expressing that dependency is as simple as having one + bean method call another: + + In the example above, the foo bean recevies a + reference to bar via constructor injection. +
+ +
+ Receiving lifecycle callbacks + + Beans created in a Configuration-class supports the regular + lifecycle callbacks. Any classes defined with the @Bean annotation can + use the @PostConstruct and @PreDestroy annotations from JSR-250, see + the section on JSR-250 + annotations for further details. + + The regular Spring lifecycle callbacks are fully + supported as well. If a bean implements InitializingBean, + DisposableBean, or Lifecycle, their + respective methods will be called by the container. + + The standard set of *Aware interfaces such as + BeanFactoryAware, + BeanNameAware, + MessageSourceAware, + ApplicationContextAware, + etc. are also fully supported. + + The @Bean annotation supports + specifying arbitrary initialization and destruction callback methods, + much like Spring XML's init-method and + destroy-method attributes to the bean + element: + + Of course, in the case of Foo above, it would be + equally as valid to call the init() method directly + during construction: + + + Remember that because you are working directly in Java, you + can do anything you like with your objects, and do not always need + to rely on the container! + +
+ +
+ Specifying bean scope + +
+ Using the <interfacename>@Scope</interfacename> + annotation + + You can specify that your beans defined with the + @Bean annotation should have a + specific scope. You can use any of the standard scopes specified in + the Bean Scopes + section. + + The StandardScopes class provides string + constants for each of these four scopes. SINGLETON is the default, + and can be overridden by using the + @Scope annotation: +
+ +
+ <code>@Scope and scoped-proxy</code> + + Spring offers a convenient way of working with scoped + dependencies through scoped + proxies. The easiest way to create such a proxy when using + the XML configuration is the <aop:scoped-proxy/> + element. Configuring your beans in Java with a @Scope annotation + offers equivalent support with the proxyMode attribute. The default + is no proxy (ScopedProxyMode.NO) but you can + specify ScopedProxyMode.TARGET_CLASS or + ScopedProxyMode.INTERFACES. + + If we were to port the the XML reference documentation scoped + proxy example (see link above) to our + @Bean using Java, it would look like + the following: +
+ +
+ Lookup method injection + + As noted in the core documentation, lookup method + injection is an advanced feature that should be comparatively + rarely used. It is useful in cases where a singleton-scoped bean has + a dependency on a prototype-scoped bean. Using Java for this type of + configuration provides a natural means for implementing this + pattern. Note that the example below is adapted from the + example classes and configuration in the core documentation linked + above. + + JavaConfig can easily create a subclass of + CommandManager where the abstract + createCommand() is overridden in such a way that it + 'looks up' a brand new (prototype) command object: +
+
+ +
+ Customizing bean naming + + By default, Configuration-classes uses a + @Bean method's name as the name of the + resulting bean. This functionality can be overridden, however, using + the name attribute. +
+
+ +
+ Defining bean metadata within components + + Spring components can also contribute bean definition metadata to + the container. This is done with the same @Bean + annotation used to define bean metadata within + @Configuration annotated classes. Here is a simple + example + + + + This class is a Spring component and has application specific code + contained in its DoWork method. However, it + also contributes a bean definition that has a factory method referring + to the method publicInstance. The + @Bean annotation identifies the factory method and + also other bean definition properties, such as a qualifier value via the + @Qualifier annotation. Other method level + annotations that can be specified are @Scope, + @Lazy, and custom qualifier annotations. Autowired + fields and methods are supported as before with the additional support + for autowiring of @Bean methods, as shown in the example below + + + + Note the use of autowiring of the String + method parameter country to the value of the + Age property on another bean named + privateInstance. A Spring Expression Language element + is used to define the value of the property via the notation #{ + <expression> }. For @Value + annotations, an expression resolver is preconfigured to look for bean + names when resolving expression text. + + The @Bean methods in a Spring component are + processed differently than their counterparts inside a Spring + @Configuration class. The difference is that + @Component classes are not enhanced with CGLIB to + intercept the invocation of methods and fields. CGLIB proxying is the + means by which invoking methods or fields within + @Configuration classes' @Bean + methods create bean metadata references to collaborating objects and do + not invoke the method with normal Java semantics. + In contrast, calling a method or field within a + @Component classes' @Bean method + has standard Java semantics. +
+
Naming autodetected components @@ -6643,7 +6743,7 @@ public class MovieFinderImpl implements MovieFinder { @Scope annotation as well. Simply provide the name of the scope within the annotation, such as: - @Scope("prototype") + @Scope(StandardScopes.PROTOTYPE) @Repository public class MovieFinderImpl implements MovieFinder { // ... @@ -6728,96 +6828,6 @@ public class CachingMovieCatalog implements MovieCatalog { per-class.
- -
- Defining bean metadata within components - - Spring components can also contribute bean definition metadata to - the container. This is done with the same @Bean - annotation used to define bean metadata within - @Configuration annotated classes. Here is a simple - example - - - - This class is a Spring component and has application specific code - contained in its DoWork method. However, it - also contributes a bean definition that has a factory method referring - to the method publicInstance. The - @Bean annotation identifies the factory method and - also other bean definition properties, such as a qualifier value via the - @Qualifier annotation. Other method level - annotations that can be specified are @Scope, - @Lazy, and custom qualifier annotations. Autowired - fields and methods are supported as before with the additional support - for autowiring of @Bean methods, as shown in the example below - - - - Note the use of autowiring of the String - method parameter country to the value of the - Age property on another bean named - privateInstance. A Spring Expression Language element - is used to define the value of the property via the notation #{ - <expression> }. For @Value - annotations, an expression resolver is preconfigured to look for bean - names when resolving expression text. - - The @Bean methods in a Spring component are - processed differently than their counterparts inside a Spring - @Configuration class. The difference is that - @Component classes are not enhanced with CGLIB to - intercept the invocation of methods and fields. CGLIB proxying is the - means by which invoking methods or fields within - @Configuration classes' @Bean - methods create bean metadata references to collaborating objects and do - not invoke the method with normal Java semantics. - In contrast, calling a method or field within a - @Component classes' @Bean method - has standard Java semantics. -